Using the multi-click manipulator

Use the multi-click manipulator to enable users to multi-click or multi-tap nodes in your Kanzi application. See Enabling the multi-click gesture for a node.

Use the Multi Click trigger to react to the multi-click gesture. For example, you can change the appearance of a node when the user multi-clicks or multi-taps that node. See Using the Multi Click trigger.

The multi-click manipulator is one of the input manipulators you can use to add gesture recognition to nodes in your Kanzi application. You can assign the input manipulators through the Kanzi Engine API. See Using input manipulators.

To enable the click gesture for nodes, use the click manipulator. See Using the click manipulator.

Learn how to use the multi-click manipulator by completing a tutorial. See Tutorial: Pan, zoom, tap.

Enabling the multi-click gesture for a node

This section explains how you can enable the multi-click gesture for any node. To enable double-click for a Button node, see Enabling the double-click gesture for a Button node.

To enable the multi-click gesture for a node:

  1. In Kanzi Studio create a project using the Application template.
  2. In the Project create a node for which you want to enable the multi-click gesture.
    For example, create an Empty Node 2D node, name it MultiClickNode, and add content to the node.
  3. In the Project select the node you created in the previous step, in the Properties add the Hit Testable property, and set it to enabled.
    When you enable this property you enable the user to pick a node.
    By default hit testing is enabled for the Button, List Box Item Container, Scroll View, and Slider nodes. See Defining which node receives user input.
  4. In the Project press Alt and right-click the node you created and select Alias.
    Kanzi Studio creates an alias pointing to the node from which you created the alias and adds it to the resource dictionary of its nearest ancestor node that contains a resource dictionary.
    Access alias target nodes using the # sign followed by the name of the alias.
  5. Select File > Export > Export KZB.
    Kanzi Studio creates the kzb file and configuration files from your Kanzi Studio project. Kanzi Studio stores the exported files in the <ProjectName>/Application/bin directory or the location you specify in the Binary Export Directory property in Project > Properties. The kzb file contains all nodes and resources from your Kanzi Studio project, except the resources you mark in a localization table as locale packs.
    When you run your Kanzi application from Visual Studio, your application loads the kzb file and configuration files.
  6. In Visual Studio open the solution stored in <ProjectName>/Application/configs/platforms/win32 and in the file which implements the logic of your application create and configure the multi-click manipulator:
    1. Define the handler for the multi-click message.
      For example, after the public section of the class which implements the logic of your application add:
      private:
      
          // Define the handler for the MultiClickManipulator::MultiClickMessage message from the nodes 
          // that have an input manipulator which generates the multi-click message.
          void onNodeMultiClicked(MultiClickManipulator::MultiClickMessageArguments& messageArguments)
          {
              // Add the code that handles the multi-click event.
          }
    2. In the onProjectLoaded() function create a MultiClickManipulator manipulator and subscribe to its message.
      For example, add:
          virtual void onProjectLoaded() KZ_OVERRIDE
          {
              ScreenSharedPtr screen = getScreen();
              Domain* domain = getDomain();
      
              // Get the MultiClickNode node using its alias.
              NodeSharedPtr multiClickNode = screen->lookupNode<Node>("#MultiClickNode");
      
              // Create an input manipulator that generates multi-click messages.
              MultiClickManipulatorSharedPtr multiClickManipulator = MultiClickManipulator::create(domain);
      
              // Add the input manipulator to the MultiClickNode node.
              multiClickNode->addInputManipulator(multiClickManipulator);
      
              // Set the number of expected clicks to three. The default number of expected clicks is two.
              // The input manipulator recognizes this number of clicks as a multi-click gesture.
              multiClickManipulator->setExpectedClicks(3);
      
              // Set the timeout of the multi-click to 500 ms. The default timeout is 250 ms.
              // If the time between each click does not exceed this value,
              // the input manipulator recognizes these clicks as a multi-click gesture.
              multiClickManipulator->setTimeout(chrono::milliseconds(500));
      
              // Subscribe to the MultiClickManipulator::MultiClickMessage message at the MultiClickNode node.
              // The MultiClickManipulator manipulator generates this message when the user multi-clicks the node.
              multiClickNode->addMessageHandler(MultiClickManipulator::MultiClickMessage, bind(&MyProject::onNodeMultiClicked, this, placeholders::_1));
          }
  7. Build and run your application. See Deploying Kanzi applications.
    In the application multi-click or multi-tap the node for which you enabled the multi-click gesture. The application executes the behavior that you defined in the handler for the MultiClickMessage message.

Using the Multi Click trigger

Use the Multi Click trigger to react to the multi-click gesture. For example, you can change the appearance of a node when the user multi-clicks or multi-taps that node.

To use the Multi Click trigger:

  1. Enable the multi-click gesture for a node. See Enabling the multi-click gesture for a node.
  2. Define the behavior that you want to set with the Multi Click trigger.
    For example, create a state manager where you define the states which set the appearance of a node when the Multi Click trigger is set off repeatedly. See Creating a state manager.
  3. In the Project select the node to which you want to add the trigger, and in the Node Components > Triggers section add the Multi Click trigger.
  4. In the trigger you created in the previous step click Trigger Settings and in the Trigger Settings Editor disable the Set Message Handled property.
    When you disable the Set Message Handled property, this trigger intercepts the message, but does not stop it. This way you let the input manipulator handle the message.
  5. In the trigger you created, in the Add dropdown menu select an action and configure it.
    For example, select the Next State action, and in the action settings set:
  6. Select File > Export > Export KZB.
  7. Build and run your application. See Deploying Kanzi applications.
    In the application multi-click or multi-tap the node for which you enabled the multi-click gesture.

Using the multi-click manipulator in the API

For details, see the MultiClickManipulator class in the API reference.

See also

Tutorial: Pan, zoom, tap

Handling user input

Using the click manipulator

Using the long-press manipulator

Deploying Kanzi applications

Using triggers